Skip to content

fix(a11y): add skip link, landmark labels, and sidebar navigation for screen readers#10390

Open
bmatar wants to merge 1 commit intoshadcn-ui:mainfrom
bmatar:fix/a11y-landmarks-keyboard
Open

fix(a11y): add skip link, landmark labels, and sidebar navigation for screen readers#10390
bmatar wants to merge 1 commit intoshadcn-ui:mainfrom
bmatar:fix/a11y-landmarks-keyboard

Conversation

@bmatar
Copy link
Copy Markdown

@bmatar bmatar commented Apr 14, 2026

The docs site scores 100 on Lighthouse accessibility and has solid semantic HTML throughout. These changes add landmark labels and a skip link to further improve navigation for screen reader and keyboard-only users.

Issues identified using Tactual, a screen-reader navigation cost analyzer:

  • No skip-to-content link. Keyboard users must Tab through 36–50 items (header + entire sidebar) to reach page content.
  • Sidebar is not a navigation landmark. Screen reader users cycling landmarks cannot jump to the docs sidebar — it renders as a <div>.
  • Landmarks are unlabeled. The <header>, <footer>, and <nav> have no aria-label, making them indistinguishable when navigating by landmark.

Changes (zero visual impact except skip link on Tab focus)

File Change
skip-to-content.tsx (new) Skip-to-content link, visible only on keyboard focus
layout.tsx Add skip link + id="content" on <main>
sidebar.tsx <div><nav aria-label="Docs sidebar"> for non-collapsible sidebar
main-nav.tsx aria-label="Main" on <nav>
site-header.tsx aria-label="Site header" on <header>
site-footer.tsx aria-label="Site footer" on <footer>

Note: the sidebar.tsx change is in the registry — it improves the distributed Sidebar component for projects using collapsible="none".

Verification

  • NVDA screen reader testing (Windows): all landmarks announced correctly when cycling with D key
  • Skip link: Tab → "Skip to content" appears → Enter → focus moves to main content
  • Tabbing past sidebar: reduced from 36–50 Tab presses to 1 (skip link) or 1 landmark jump (D key)
  • Visual regression: zero difference except skip link on focus
  • Lint, typecheck, prettier: all pass

🤖 AI-assisted (Claude). All changes manually verified with NVDA.

… screen readers

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@vercel
Copy link
Copy Markdown
Contributor

vercel Bot commented Apr 14, 2026

@bmatar is attempting to deploy a commit to the shadcn-pro Team on Vercel.

A member of the Team first needs to authorize it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant